home *** CD-ROM | disk | FTP | other *** search
/ Gigarom 1 / Gigarom Macintosh Archives (Quantum Leap)(CDRM1080320)(1993).iso / FILES / HYP / A-B / BibliographyManager.cpt / Bibliography Manager II / Bib. Man. II Docs / Bib. Man. II docs - text < prev   
Text File  |  1990-09-25  |  28KB  |  238 lines
  1.  
  2.              INSTRUCTIONS FOR "BIBLIOGRAPHY MANAGER II"
  3.  
  4.  
  5.  
  6. About this Manual
  7.  
  8.     Since most Macintosh users like to explore software before exploring manuals, this manual is divided into three sections:  Basics, Example, and Reference.  Those who wish their exploration of Bibliography Manager II to proceed with the minimum of interference from tiresome documentation or mundane examples can confine their perusing to the Basics section (and it should be read before proceeding!) and Shareware Notice, saving the Reference section for when they are hopelessly adrift.  Others are encouraged to try a more hands-on approach by following the instructions for creating a sample Bibliography in the Example section.
  9.  
  10.  
  11.  
  12.                     BASICS
  13.  
  14.  
  15.  
  16. I.  Which Stacks do what
  17.  
  18.     In order to make use of the database and associated programming which comprise Bibliography Manager II, you need to have three stacks:  (1) "Bibliography Manager II"; (2) "Bib. Man. II Cards"; and (3) "Bib. Man. II Details".
  19.  
  20.     "Bibliography Manager II" contains two types of cards:  a "Main Menu" card that contains buttons for some file operations, and some "program control" cards which you needn't worry about (they are used by some of the operations, but the operations do all their own housekeeping).  You will need to go to this stack only when you want to perform one of the following file operations:  (1) create a new Bibliography File, (2) save a copy of a Bibliography File, or (3) update the links between a Bibliography File and its associated Details Stack.
  21.  
  22.     The information part of the database is contained in what I term "Bibliography Files" and their associated "Details Stacks".  You can create any number of Bibliography Files, but you can only work with them one at a time.  Each entry in your Bibliography File will have its own card containing the Reference Number, the information on the reference itself, and sets of buttons that allow you to perform all the various operations.  Each Bibliography File has a "Details Stack" associated with it.  You can use these Details Stacks to store information such as abstracts or comments on each entry in the Bibliography File.  When you create a Details Stack, you are asked to choose between having either one or two scrolling fields in which to enter information, and to provide appropriate titles for these fields.  The stack "Bib. Man. II Cards" is the template stack  from which all Bibliography File stacks are created; the stack "Bib. Man. II Details" is the template stack  from which all Details Stacks are created.
  23.  
  24.  
  25.  
  26. II.  Getting Started
  27.  
  28.  
  29.     Before you start using Bibliography Manager II, be sure that you have made backup copies of all three stacks!
  30.  
  31.     The first time that you use Bibliography Manager II, you will want to create a Bibliography File (don't use the stacks "Bib. Man. II Cards" and "Bib. Man. II Details" for storing information; they should be left as you received them).  To create a Bibliography File, open the stack "Bibliography Manager II" and choose "Make a New Bibliography File".  Once you have created a Bibliography File you can open it directly whenever you want to use it.
  32.     Once you have created your own Bibliography File, you can begin to store entries.  Use the "Type in an entry" command if you want to simply type information into the file. If you want to import information from a text file, you can use the "Read in a file" command.  I would strongly recommend that you read the explanation of this command in the Reference section of this manual before attempting to read in information from text files.
  33.  
  34.  
  35. III.  Proper Format for Information
  36.  
  37.  
  38.     In order that Bibliography Manager II can properly sort your Bibliography Files alphabetically, you should use the standard format when entering information into them.  The most critical field is the Author field.  Each author name should be on a separate line, last name first followed by a comma, then first name(s) or initial(s) separated by spaces.  Periods after initials are optional.   The remaining fields should contain the appropriate information with no preceding or trailing punctuation marks except if used to identify an abbreviation (e.g., in the Publication field if journal names are abbreviated).
  39.  
  40.     If you use the proper format for your entries, Bibliography Manager II will be able to sort and export your entries in proper alphabetical order and allow you great flexibility in creating export formats for your entries (for example, there are 1,656 possible combinations of order/punctuation of Author names).
  41.  
  42.  
  43.  
  44.                     EXAMPLE
  45.  
  46.  
  47. Follow the steps below to create a sample Bibliography from the "Sample Exchange File" document included with Bibliography Manager II:
  48.  
  49.  
  50.     1.  Copy the files "Bibliography Manager II", "Bib. Man. II Cards", "Bib. Man. II Details", and "Sample Exchange File" to your hard disk or working disk (in any folder you want).
  51.  
  52.     2.  Open the stack "Bibliography Manager II" from the Finder, or open HyperCard, choose "Open Stack" from the File menu, and locate and open "Bibliography Manager II".
  53.  
  54.     3.  You should be shown the Shareware notice; click the button "Just Trying it out" for now.
  55.  
  56.     4.  Click the button "Create a New Bibliography File".
  57.  
  58.     5.  You will be shown a reminder that you need to have the stacks "Bib. Man. II Cards" and "Bib. Man. II Details" available to successfully complete the operation.  Click the "Continue" button unless you haven't copied them as instructed in step 1.
  59.  
  60.     6.  HyperCard may ask you where the stack "Bib. Man. II Cards" is (if it hasn't searched the folder that it's in before).  You will be given the standard Macintosh "Open" dialog box; use it to locate this stack and then choose "Open".
  61.  
  62.     7.  Once the stack "Bib. Man. II Cards" is open you will be presented with the standard HyperCard "New Stack" dialog box; enter a name for this stack (e.g., "Sample Bibliography";  DO NOT use "Bib. Man. II Cards") and click the "New" button.
  63.  
  64.     8.  Once this new Bibliography File is created you will be informed that Bibliography Manager II is next going to create the corresponding Details stack; choose "OK".
  65.  
  66.     9.  Once the stack "Bib. Man. II Details" is open you will be presented with the standard HyperCard "New Stack" dialog box; enter a name for this stack (e.g., "Sample Bibliography Details";  DO NOT use "Bib. Man. II Details") and click the "New" button.
  67.  
  68.     10.  You will next be asked whether you want one or two information fields on the cards in the Details stack.  Make your selection and follow the subsequent instructions for assigning names to them.
  69.  
  70.     11.  You should now be informed that a new Bibliography File has successfully been created!
  71.  
  72.     12.  The next sep is to read in information from the file "Sample Exchange File".  To do this, click the button "Read in a file" at the bottom of the card.  (NOTE:  if this button does not appear at the bottom of your card it is hopefully because the"Input/Output" menu is not currently selected.  To select it, click the area that reads "Input/Output" along the top of the bottom portion of the card; that area should now appear in reverse video, and (among others) the "Read in a file" button should now appear.)
  73.  
  74.     13.  You should now be shown the input instruction card.  You don't have to read it now, but it will give you some idea of how your own files might need to be modified so that they can be read in (this information also appears in the "Reference" section of this manual).  Click the "Read in an Exchange File" button.
  75.  
  76.     14.  Use the "Open" dialog box to locate and select the file "Sample Exchange File" and click "Open".
  77.  
  78.     15.  Once the file is read in you can experiment with the many features of Bibliography Manager II.  Look at the operations that are available under the three menus ("Searching", "File Maintenance", and "Input/Output").  Some possibilities for experimentation are:
  79.     a.  Click on the title of any field to perform a "Quick Search" (see "Reference" for details on this feature); also try out the buttons in the "Searching" menu.  
  80.     b.  Since the file includes duplicate entries and is not in alphabetical order you can try out the various "File Maintenance" features.  
  81.     c.  Try typing in your own entry or deleting an entry or two.
  82.     d.  Add details to a few entries.
  83.     e.  (HINT:  I suggest you do a bit of reading in the "Reference" section before attempting to write information to a text file.)
  84.  
  85.  
  86.  
  87.                     REFERENCE
  88.  
  89.  
  90. I.  Performing Operations
  91.  
  92. A.  Bibliography Manager II Main Menu:  File Operations
  93.  
  94.     All file operations (e.g., creating new  or saving copies of Bibliography Files) should be done using the buttons on the Main Menu card in the stack Bibliography Manager II.
  95.  
  96.     1.  Create a New Bibliography File:  clicking this button allows you to create a new (empty) Bibliography File and its associated Details Stack.  NOTE: be sure that you have copies of the stacks "Bib. Man. II Cards" and "Bib. Man. II Details" handy before doing this.
  97.  
  98.     2.  Open a Bibliography File:  this is the same as choosing the command "Open Stack..." from the HyperCard menu.  You can open any stack, including any Bibliography Files you have created, with this command.
  99.  
  100.     3.  Save a Copy of a Bibliography File:  if you click this button you will be informed how you can save copies of these stacks.  You may either keep their current names, or you can rename them.  If you do the latter, the program will automatically update the links between the Bibliography File and the Details Stack.  
  101.  
  102.     4.  Update Links:  use this command to update the links between a Bibliography File and its Details Stack if you have renamed either stack (if you rename either a Bibliography File or a Details Stack in the Finder all Bibliography File-to-Details Stack links will be lost).  If you have renamed the Details Stack, just select (when prompted) the Bibliography File whose Details Stack name was changed, then choose "Change Details Stack" (and "Change") and select the newly named Details Stack.  If you have renamed the Bibliography File stack, it will appear as though the links are OK when you are asked to choose an option.  Choose "Change Details Stack" (and "Change") and select the one indicated; this will correct the links in the Details Stack.
  103.     You can also use this command to create a new Details Stack for any Bibliography File.  Just select the Bibliography File, then choose "Change Details Stack" and "Make New".  You will then be asked to create a new Details Stack that will be linked to the Bibliography File you chose.  NOTE that if you create a new Details Stack for a Bibliography File that already has one, all the links to the old Details Stack will be removed from that Bibliography File.
  104.  
  105.  
  106. B.  Operations available from within Bibliography Files
  107.  
  108.     There are four categories of operations available from within a Bibliography File:  
  109. (1) General, (2) Searching, (3) File Maintenance, and (4) Input/Output.  The operations falling under the heading of General consist of the four buttons at the bottom left of a Bibliography File card, the button on the lower right that deals with the Details Stack, and the "quick search" buttons.  The other three categories of operations are available, one at a time, in the lower portion of the Bibliography File card.  The three buttons at the top of this section of the card bearing the names of these categories are used to select which category of operations is currently available.  The currently available set is shown in reverse video.
  110.  
  111.  
  112. 1.  GENERAL
  113.  
  114.     a.  Home:  takes you to the Home card.
  115.  
  116.     b.  Quit:  quits HyperCard.
  117.  
  118.     c.  Browse:  shows you all the entries in the database in order; you can stop at any time simply by clicking the mouse.
  119.  
  120.     d.  Delete:  deletes the current entry.  
  121.     If you click on this button while pressing the Option key you can delete a range of entries by entering the first and last reference numbers of the range desired when prompted.  This option comes in handy when you need to delete the bunch of references you just read in the wrong way!
  122.  
  123.     e.  Details - Add (or Show):  if the Add button is showing, clicking it will (1) create a new entry in the Details stack, (2) link up the current entry in the Bibliography File with the new Details stack entry, (3) change the Add button to Show, and (4) set you up to type in information for the Details stack entry.  
  124.     If the Show button is showing, clicking it will show you the Details entry for the current Bibliography File entry.
  125.  
  126.     f.  "Quick Search" buttons:  you can search a field at any time by clicking on the name of the field.  
  127.     There are two ways to choose a key to search for.  If you select text in any field with the mouse, and then click on any field's name, Bibliography Manager II will automatically search for the selected text in the field you clicked (HINT: you can select a word in any field by double-clicking on it).  If nothing is selected when you choose a Quick Search you will be asked to type in a key to search for; in the Author, Date, or Keywords fields, the first name or word in that field will be presented as a default search key.  Your most recent quick search key becomes the default key for subsequent quick searches in the same field.  You can repeat quick searches in the same field by holding the Option key down while clicking the Quick Search button.
  128.  
  129.     g.  Show highest Reference Number:  if you click the "Reference Number" field title while holding down the Option key you will get a dialog box showing you the last Reference Number assigned to an entry.
  130.  
  131.     h.  Clean up non-scrolling fields:  Sometimes when you read in entries from a text file the information doesn't end up in the right fields because of problems in the text file.  This can create editing problems in the two fields that do not scroll - "Date" and "Vol./Pages" - when the text in these fields goes beyond the first line.  A safety-valve for this problem has been built in.  If you click on the names of either of these two fields while holding down the Option key, the entire contents of the field will be  removed and appended to the "Keywords" field.
  132.  
  133.  
  134. 2.  SEARCHING
  135.  
  136.     a.  Search 1 Key:  allows you to search the entries in the Bibliography File for the occurrence of any word, partial word, or any group of consecutive characters in any field.  Partial word searches (the default setting) can be used to find words that may appear in singular or plural forms (e.g., "communit" will find either community or communities), or groups of characters or words you expect to find occurring consecutively (e.g., "hard disk").  Choosing whole word searches will ensure that only exact matches are found (e.g., "williams" will not locate "williamson").
  137.     When you click this button, the first subsequent entry in the Bibliography File that matches your search criteria will be located and become the current entry.  You can then use the "Find Next Match" button to locate more entries that match your criteria.
  138.  
  139.     b.  Search 2 Keys:  similar to the above, but finds only those entries in which BOTH of the keys you specify occur.  These searches always start from the beginning of the Bibliography File.
  140.  
  141.     c.  Search & Write:  This operation allows you to select entries to be written to a text file while you are browsing or searching the Bibliography File.  It can be especially useful if you are trying to put together a list of references on a subject and don't want to hassle with searching your hard copy for pertinent entries.  The entries will be written out to the text file in alphabetical order.
  142.     Because this operation involves output to a text file, you should read about selecting an output format in the description of the "Write Selected" operation under "INPUT/OUTPUT".  
  143.     Once you have selected an output format, you will be in "Search & Write Mode".  While in this mode you can browse the Bibliography File and use all of the searching operations. When you have located an entry you want to have written to the text file click the "Write this one" button.  When you have located all the entries you wish to output, click the "End Search & Write" button.
  144.     Clicking on the "Write this one" button while pressing the Option key is equivalent to clicking the "Type in an entry" button (see below under INPUT/OUTPUT).  NOTE that the new entry will not automatically be included in those selected to be written to a text file.  This option is useful if you are putting together a bibliography for a manuscript which contains references that are not yet in your Bibliography File and you want to have all the references written out in alphabetical order.
  145.  
  146.     d.  Left Arrow:  moves one entry backward in the Bibliography File.
  147.     Click on this button while pressing the Option key to move to the first entry in the  Bibliography File.
  148.  
  149.     e.  Right Arrow:  moves one entry forward in the Bibliography File.
  150.     Click on this button while pressing the Option key to move to the last entry in the  Bibliography File.
  151.  
  152.     f.  "U-turn" Arrow:  this special arrow will appear between the left and right arrow while you are searching.  It takes you back to the last entry you were looking at after a search has located another entry.
  153.  
  154.  
  155.  
  156. 3.  FILE MAINTENANCE
  157.  
  158.     a.  Sort File:  sorts the Bibliography file in alphabetical order.  This operation also (1) checks for blank entries (actually, for entries in which the Title is blank) and asks you if you want to delete them, and (2) checks for and deletes any cards that do not belong to the stack.  After the file is sorted you will be asked if you want to renumber the file at that point.
  159.  
  160.     b.  Renumber File:  assigns consecutive numbers, starting with 1, to entries in the Bibliography file after sorting them into alphabetical order.  This operation also asks if you want to write the entire file to a text file for printing, which you may want to do if you have added new entries.
  161.  
  162.     c.  Find Duplicates:  This is a time-consuming operation, though only the computer need be tied up for the bulk of it.  What this does is find entries that have both the same (1) first word in the Author field and (2) last word in the Title field.  It then displays, in one place, each set of suspected duplicate entries and gives you the option of deleting and/or keeping each of these.  If there are more than five entries that are the same, you will have to do this more than once to isolate and delete the extras.
  163.  
  164.     d.  Compact Stack:  performs the HyperCard Menu function "Compact Stack", which reduces overweight stacks to the smallest possible size for storage, on both the Bibliography File and its Details stack.
  165.  
  166.     e.  Show Menu Bar (or Hide Menu Bar):  shows (or subsequently hides) the standard HyperCard Menu Bar at the top of the screen.
  167.  
  168.     f.  Bib. Man. II Menu:  takes you to the Bibliography Manager II Main Menu.
  169.  
  170.  
  171. 4.  INPUT/OUTPUT
  172.  
  173.     a.  Type in entries:  allows you to add a new entry to the Bibliography File by creating a blank card for you to type into.  The new entry is automatically given a Reference Number.
  174.  
  175.     b.  Read in a file:   Bibliography Manager II can read in text files as long as they are formatted so that the right information can be put into the right fields.  If the file you want to read in is a "Bibliography Manager II Exchange File" - that is, if the file was created by Bibliography Manager II using the output format "Bib. Man. II File Exchange" - click the button "Read in an Exchange File".  Otherwise you will need to specify your input file's format.  
  176.     To describe the required format for the information in your text file, I will use the standard database terms "field" and "record".  In this case, a "field" corresponds to a field on the cards in a Bibliography File (i.e. Author, Date, etc.) and a "record" corresponds to an individual card or entry.  Any text file you want to read in must have the following attributes:
  177.  
  178. 1.  The information for one record must be contiguous;
  179. 2.  Within the information for one record, the information to be put into one field must be contiguous (e.g., no fair having some author names, then the date, then more authors);
  180. 3.  The information for each field must be terminated by a delimiter that is either a SINGLE character or a carriage return, and that delimiter should be the same for the entire file;
  181. 4.  The information for each record may also optionally be terminated by a delimiter or carriage return; the record delimiter cannot be the same as the field delimiter.
  182.  
  183. To specify the format of your file click the "Specify Input File Format" button.
  184.     When you click this button, you will be prompted for four categories of information about your text file.  First, you will be asked to specify in what order the information for each field appears in; simply click on the field names in the order that the corresponding information appears in your text file.  Secondly, if your input file includes author names, you will be asked to specify (1) the order in which the first author name appears, (2) the order in which the second author name(s) appear(s), and (3) whether there are commas between the author names.  Next you will be prompted to specify the field delimiter - choose either "Line per field" (if the information for each field is terminated by a carriage return) or "Set delimiter".  Lastly you will be asked to specify whether or not you have record delimiters in your text file, and if so, what they are.
  185.     Here are a few things to keep in mind when you are setting up a text file to be read in:
  186.   
  187. 1.  If you use special characters for your field and/or record delimiters, make sure that they do not appear in the text of the information itself.
  188. 2.  Be sure that you have a delimiter after the last field for each record if you are not using record delimiters.  (This is not a bad idea even if you are using record delimiters, as it will make the operation go more quickly).
  189. 3.  Be sure that you have field delimiters for each field in each record even if there is no information for that field.
  190. 4.  Blank lines between records will be ignored (EXCEPT in "Line per record" format); HOWEVER, if you are using "Line per field" format be sure that there is one line for each field even if there is no information for that field.
  191.  
  192.     The entries read in are added at the end of the Bibliography File and automatically assigned Reference Numbers.  Once your file has been read in (or you have stopped the read operation), you will be returned to the card of the first entry that was read in.  HINT:  If you want to delete the entries you just read in for some reason, you can easily do it by (1) noting the Reference Number of the first entry read in, (2) clicking on the "Reference Number" field title while pressing the Option key - this gives you the last Reference Number read in, and (3) clicking "Delete" while pressing the Option key to delete a range of entries and entering the first and last Reference Numbers read in. 
  193.  
  194.  
  195.     c.  Write selected:  This operation allows you to specify, using Reference Numbers, the entries you would like written to a text file using whatever output format you choose.  The following discussion of output formats applies to all output operations.
  196.  
  197.     Output Formats:
  198.     Bibliography Manager II comes with one predefined output format.  It is designed solely for exporting information to another Bibliography Manager II Bibliography File.  All other output formats are designed by the user.  These output formats, once designed, can be saved for future use with any Bibliography File.
  199.     The default output format for any Bibliography File is the one most recently used with that file (if none has been used, then you must choose or design one).  The name of that output format will be shown in the dialog box that asks you to decide on the output format to use.  If you elect not to use the current output format, you can choose either (1) "Select" to use the predefined file exchange format (entitled "Bibliography Manager II File Exchange") or one you have previously designed and saved or (2) "Design New" to design a new format.
  200.     If you elect to design a new output format you will be guided through this exercise by the program.  Basically, you design the output format by clicking on the buttons that represent the information fields in your Bibliography File and possible punctuation or other characters in the order you wish them to appear in the output.  The format design will appear in the box immediately above them.  Use the "Clear Format" button to undo mistakes.   [Note:  One space (◊) is inserted before each item of bibliography information (e.g., Author, Date) and each record (all the information from one card) is followed by two carriage returns].   If you elect to include Author names in your output format, then you will be asked to specify formats for the order of, and punctuation of and between, the first author and co-author(s) names.  When you have finished designing the format, click "Create Format".  You will then be shown an example of the format you have designed.
  201.     Once you have created an output format, you can choose either (1) "Design a new format" to start over, (2) "Use format" to use the format without saving it, or (3) "Save format" to name and save the format for future use before using it.
  202.  
  203.     The first thing you will be asked to do when you click the "Write Selected" button is to decide on an output format for your entries.  Next you will be asked to choose a name for the output file.  Then you will be presented with a program card on which you can type, separated by spaces or returns, the Reference Numbers (or ranges of Reference Numbers) of the entries that you would like written to the file.  You may enter the Reference Numbers in any order; the program will arrange the entries in alphabetical order as it writes them to the file.  Once you have typed in all the desired Reference Numbers, click the "Click Here when Finished" button to have these entries written to the file.  
  204.  
  205.     d.  Write all entries:  writes all entries in the Bibliography File, in their current order, to a text file using whatever output format you choose (see discussion of output formats under the information for "Write Selected" above).
  206.  
  207.     e.  Search & Write:  see the discussion of the Search & Write operation under "SEARCHING" above.
  208.  
  209.  
  210. C.  Operations available from within Details Stacks:
  211.  
  212.     1.  Delete:  deletes the current Details entry and removes the link to the corresponding entry in the Bibliography File.  This button is only available if you have entered the Details stack by clicking the "Add" or "Show" button in a Bibliography File.
  213.  
  214.     2.  Write to Text:  writes all fields (with their titles) of the current Details entry to a text file.  This button is not available if you are in "Search & Write Mode".
  215.  
  216.     3.  Read from Text:  reads in the entires contents of a text file and appends it to the first data field in the current Details stack entry.  This button is not available if you are in "Search & Write Mode".
  217.  
  218.     4.  Return to Bibliography File:  returns you to your place in the Bibliography File.
  219.  
  220.  
  221.  
  222. D.  Miscellaneous Information
  223.  
  224.     1.  Version numbers:  you can find out both the version number and the date of the last program upgrade of the stack "Bibliography Manager II" and of any Bibliography File.  
  225.     To show (or hide) this information for the stack "Bibliography Manager II", click the scrollwork at the bottom of the Main Menu card; the version number and last date modified will appear at the bottom of the card.
  226.     To see this information for a Bibliography File, click on the stack name display (upper left corner of the card) while pressing the Option key; a dialog box will apprise you of the information.
  227.     You can use this information to determine if you have the latest version of the stackware in operation should there be further upgrades of Bibliography Manager II.
  228.  
  229.  
  230.                    SHAREWARE NOTICE
  231.  
  232.      The set of stacks comprising the HyperCard application Bibliography Manager II - "Bibliography Manager II", "Bib. Man. II Cards", and "Bib. Man. II Details" - is being offered to all interested Macintosh users as shareware.  If you find any problems while using these stacks, please let me know!  I will fix them.  If you decide to keep and use any part of these stacks, please send $20 with your name and address to:
  233.  
  234.                       David Tremmel
  235.                         19 Hammond St. Apt. 2
  236.                  Waltham, MA  02154
  237.  
  238.